WDK Core Documentation Refactor #64

ihsraham · 2026-01-17T11:27:01Z

This PR refactors the monolithic sdk/core-module/usage.md into 8 granular "How-to" guides.

This refactor was validated using a "User Zero" approach: verification was performed by explicitly following the newly created guides step-by-step from a fresh state to ensure accuracy and reproducibility. During this process, several critical gaps and inaccuracies were identified and resolved.

Resolved Issues

1. Replaced Unavailable TON Bridge

Issue: @tetherto/wdk-protocol-bridge-usdt0-ton is not available on NPM.
Resolution: Removed TON bridge references and replaced them with the working @tetherto/wdk-protocol-bridge-usdt0-evm package in protocol-integration.md.

2. Corrected Failover Middleware

Issue: References to @tetherto/wdk-wrapper-failover-cascade were incorrect (404).
Resolution: Updated documentation to use @tetherto/wdk-provider-failover with the correct createFallbackWallet wrapper pattern (moved out of registerMiddleware).

Corrections & Value Additions

2. Configuration Corrections (TON)

Invalid Config Structure: The docs had a flat config (tonApiKey, tonApiEndpoint) but the SDK requires a nested tonClient object.
- Correction: Updated guides/wallet-registration.md and configuration.md to use the correct structure:
```
tonClient: { secretKey: '...', url: '...' }
```
Missing API Key Instructions: Users were blocked without instructions on obtaining keys.
- Addition: Added links to TON Center (https://t.me/toncenter) and their docs (https://docs.ton.org/...) in guides/wallet-registration.md.
Network/Endpoint Mismatch: Users faced "Network not allowed" errors when mixing Testnet keys with Mainnet endpoints.
- Addition: Added "Note" callouts explicitly listing Mainnet vs. Testnet endpoints for TON and Ethereum.

3. Functional Verification Fixes

Installation Instructions: Initial guides missed npm install steps for wallet and protocol packages.
- Correction: Added explicit installation sections to wallet-registration.md and protocol-integration.md.
Invalid Test Data: The TON recipient address in transactions.md was malformed (checksum error).
- Correction: Replaced with a valid address (UQCz5ON7jj...).
Unusable Transaction Defaults: The Ethereum example sent 1 ETH, far exceeding faucet limits.
- Correction: Reduced to 0.001 ETH.
Chain Mismatch: The Ethereum example used a Mainnet RPC but users typically have Testnet funds.
- Addition: Added callouts for Sepolia RPCs and Faucet links (Google Cloud, TON Testgiver).

4. Visual & Style Improvements

GitBook Hints: GitBook-native hints ({% hint style="info" %}) for consistent rendering.
Usage Landing Page: Updated usage.md index to use a Cards Grid Layout, matching the design of other module pages.

File Changes

Refactor: sdk/core-module/usage.md -> Splitted into sdk/core-module/guides/*.md
Update: sdk/core-module/configuration.md (Fixed TON config)
Update: sdk/core-module/guides/protocol-integration.md (Removed TON bridge, replaced with EVM bridge)
Update: sdk/core-module/guides/middleware.md (Updated Failover section to use createFallbackWallet wrapper pattern)

Verification Report

Guide	Status	Notes
Installation	✅ Verified	Installed `@tetherto/wdk` successfully.
Instantiation	✅ Verified	Instance created and seed generated.
Register Wallets	✅ Verified	Fixed: Updated TON configuration structure & added missing API key context.
Manage Accounts	✅ Verified	Fixed: Added network/key mismatch (Testnet vs Mainnet) warning.
Send Transactions	✅ Verified	Fixed: Updated invalid TON address, added faucet links, fixed Sepolia RPC mismatch.
Integrate Protocols	✅ Verified	Velora verified. USDT0 Bridge (TON) removed, replaced with EVM example.
Middleware	✅ Verified	Logging verified. Failover updated to correct Wrapper usage (not `registerMiddleware`).
Error Handling	✅ Verified	Confirmed error patterns and `dispose()` functionality.

lucas-tortora

Beautiful PR :) Just a few comments regarding style and structure.

lucas-tortora · 2026-01-20T13:08:26Z

sdk/core-module/guides/account-management.md

+{% endcode %}
+
+{% hint style="info" %}
+The WDK instance caches accounts. calling `getAccount` twice for the same index returns the same object instance.


Suggested change

The WDK instance caches accounts. calling `getAccount` twice for the same index returns the same object instance.

The WDK instance caches accounts. If you call `getAccount` twice using the same index, the function will return the same `Account` object instance.

10e32b09e20f121467ed079ca03757a1656d7a10

lucas-tortora · 2026-01-20T13:09:00Z

sdk/core-module/guides/account-management.md

+{% hint style="warning" %}
+**Network Mismatch Warning**
+Ensure your WDK instance configuration matches your account environment.
+*   If using **Testnet** keys, ensure you registered the wallet with a **Testnet RPC**.


Please add links to the RPCs

10e32b09e20f121467ed079ca03757a1656d7a10

lucas-tortora · 2026-01-20T13:09:31Z

sdk/core-module/guides/account-management.md

+Ensure your WDK instance configuration matches your account environment.
+*   If using **Testnet** keys, ensure you registered the wallet with a **Testnet RPC**.
+*   If using **Mainnet** keys, ensure you registered the wallet with a **Mainnet RPC**.
+Using a Mainnet key on a Testnet RPC (or vice versa) will result in "Network not allowed" or 0 balance errors.


Suggested change

Using a Mainnet key on a Testnet RPC (or vice versa) will result in "Network not allowed" or 0 balance errors.

Using a Mainnet key on a Testnet RPC (or vice versa) will result in "Network not allowed" or zero balance errors.

We should spell out numbers unless they are being used in opertions.

10e32b09e20f121467ed079ca03757a1656d7a10

lucas-tortora · 2026-01-20T13:12:47Z

sdk/core-module/guides/account-management.md

+
+## View Addresses
+
+Once you have an account object, you can retrieve its public blockchain address.


Suggested change

Once you have an account object, you can retrieve its public blockchain address.

Once you have an account object, you can retrieve its public blockchain address using the `getAddress` function.

10e32b09e20f121467ed079ca03757a1656d7a10

lucas-tortora · 2026-01-20T13:13:13Z

sdk/core-module/guides/account-management.md

+
+## Check Balances
+
+You can check the native token balance of any account (e.g., ETH on Ethereum, TON on TON).


Suggested change

You can check the native token balance of any account (e.g., ETH on Ethereum, TON on TON).

You can check the native token balance of any account (e.g., ETH on Ethereum, TON on TON) by using the `getBalance()` function.

10e32b09e20f121467ed079ca03757a1656d7a10

lucas-tortora · 2026-01-20T14:07:03Z

sdk/core-module/guides/transactions.md

+## Multi-Chain Transactions
+
+You can orchestrate payments across different chains in a single function by acting on multiple account objects sequentially.
+


Suggested change

The following example will:

1. Retrieve an ETH and ton account using the `getAccount()` method.

2. Send ETH and `await` the transaction.

3. Send TON and `await` the transaction.

lucas-tortora · 2026-01-20T14:07:45Z

sdk/core-module/guides/wallet-registration.md

+npm install @tetherto/wdk-wallet-evm @tetherto/wdk-wallet-ton @tetherto/wdk-wallet-btc
+```
+
+## Example: Registering Multiple Wallets


Suggested change

## Example: Registering Multiple Wallets

## Register Multiple Wallets

lucas-tortora · 2026-01-20T14:08:22Z

sdk/core-module/guides/wallet-registration.md

+
+## Installation
+
+Install the wallet managers for the blockchains you want to support:


Please add link to the wallet modules home page.

lucas-tortora · 2026-01-20T14:10:15Z

sdk/core-module/guides/wallet-registration.md

+```
+
+## Example: Registering Multiple Wallets
+


Suggested change

### Import the Wallet Manager Packages

lucas-tortora · 2026-01-20T14:11:31Z

sdk/core-module/guides/wallet-registration.md

+```
+{% endcode %}
+
+Then, instantiate WDK and chain the registration calls:


Suggested change

Then, instantiate WDK and chain the registration calls:

### Register the Wallets

Then, instantiate WDK and chain the registration calls:

Please add link to the instantiate doc

lucas-tortora

Beautiful PR :) Just a few comments regarding style and structure.

gatteo · 2026-01-21T10:22:43Z

SUMMARY.md

 * [All Modules](sdk/all-modules.md)
 * [Core Module](sdk/core-module/README.md) 
  * [Usage](sdk/core-module/usage.md)
+    * [Installation](sdk/core-module/guides/installation.md)


Let's merge installation and Instantiation into one.
Installation does not provide enough value.
Also use a more readable name like "Get Started" or similar

gatteo · 2026-01-21T10:28:31Z

sdk/core-module/guides/wallet-registration.md

+
+### Parameters
+
+The `registerWallet` method requires three arguments:


Add link to the method in reference page? or maybe a note saying "See full reference here"

gatteo · 2026-01-21T10:30:16Z

sdk/core-module/guides/wallet-registration.md

+    provider: 'https://eth.drpc.org'
+  })
+  // 2. Register TON
+  .registerWallet('ton', WalletManagerTon, {


I would remove Ton. Just because it's the only one that needs an API key to use, so a user cannot copy the snippet and run without configuration.

So leave only 2 modules in this example or add another wallet module that doesn't require API KEY

gatteo · 2026-01-21T11:14:24Z

sdk/core-module/guides/wallet-registration.md

+*   **Mainnet:** `https://eth.drpc.org`
+*   **Sepolia (Testnet):** `https://sepolia.drpc.org`
+{% endhint %}
+


We cannot promote specific RPCs. Maybe instead we should create a section in the "Concepts" page where we tell developers some RPCs for each network and tell them where to find more (https://chainlist.org) - Leaving the choice to developers

Here we can create a hint like "Find out more about RPCs here" or something

gatteo · 2026-01-21T11:19:43Z

sdk/core-module/guides/transactions.md

+{% endcode %}
+
+{% hint style="info" %}
+**Get Testnet Funds:** To test these transactions without spending real money, verify you are on a testnet and use a faucet:


Maybe section in the concepts page about testing funds, where to get them, what are available faucets etc.

gatteo · 2026-01-21T11:20:25Z

sdk/core-module/guides/transactions.md

+
+## Handling Responses
+
+The `sendTransaction` method returns a transaction result object. The most important field is typically `hash`, which represents the transaction ID on the blockchain. You can use this hash to track the status of your payment on a block explorer.


Link "transaction result object" to the reference page?

gatteo · 2026-01-21T11:21:50Z

sdk/core-module/guides/protocol-integration.md

+```
+{% endcode %}
+
+### Account-Level Registration


I think we can remove this section, as this is the guide for the core module not specific accounts / wallets

gatteo · 2026-01-21T11:25:42Z

sdk/core-module/guides/middleware.md

+```
+{% endcode %}
+
+## Failover Protection


The @tetherto/wdk-provider-failover wraps a specific wallet module, not the core, so maybe we should remove this guide from core module documentation and move to another section ?

…es, and improved headers

…inks

…e references

ihsraham added 11 commits January 17, 2026 12:51

docs: start refactoring core module usage - added installation guide

0fd5ab2

docs: Add WDK Core instantiation guide

994287c

docs: add core module wallet registration guide

eaa3108

docs: add core module account management guide

8dcf673

docs: add core module transactions guide

b30ab97

docs: add core module protocol integration guide

67fa9c0

docs: add core module middleware guide

16e1aa2

docs: add core module error handling guide

7e52e3e

docs: refactor core module usage page to index

a108eca

docs: update summary navigation for core module

b0225fe

docs: fix ton configuration structure in config reference

3f106fb

ihsraham changed the base branch from main to develop January 17, 2026 11:27

docs: standardize frontmatter headers for core module guides

e72c120

ihsraham marked this pull request as draft January 19, 2026 15:01

ihsraham added 5 commits January 20, 2026 08:55

docs: finalize middleware failover implementation

ce36549

docs: remove usage of unpublished ton bridge module

484107c

docs: fix gitbook callout syntax and formatting issues

766cb18

docs: add missing sidebar icon to core module usage page

f76f535

docs: update usage page to use gitbook cards layout

9a9e7a4

ihsraham marked this pull request as ready for review January 20, 2026 09:25

lucas-tortora suggested changes Jan 20, 2026

View reviewed changes

gatteo requested changes Jan 21, 2026

View reviewed changes

ihsraham added 7 commits January 22, 2026 11:41

docs: refine account management guide with clearer examples and warnings

10e32b0

docs: refine error handling guide with hints and security sections

4ffdf75

docs: add resource links to installation guide

187721d

docs: refine instantiation guide with internal links, module referenc…

4ee9aa5

…es, and improved headers

docs: standardize headers and refine middleware guide with resource l…

77ce280

…inks

docs: enhance protocol integration guide with header links and packag…

7c74349

…e references

docs: optimize installation command in protocol integration guide

96eb215

	The WDK instance caches accounts. calling `getAccount` twice for the same index returns the same object instance.
	The WDK instance caches accounts. If you call `getAccount` twice using the same index, the function will return the same `Account` object instance.

	Using a Mainnet key on a Testnet RPC (or vice versa) will result in "Network not allowed" or 0 balance errors.
	Using a Mainnet key on a Testnet RPC (or vice versa) will result in "Network not allowed" or zero balance errors.


		## View Addresses

		Once you have an account object, you can retrieve its public blockchain address.


		## Check Balances

		You can check the native token balance of any account (e.g., ETH on Ethereum, TON on TON).

		## Multi-Chain Transactions

		You can orchestrate payments across different chains in a single function by acting on multiple account objects sequentially.

+The following example will:
+. Retrieve an ETH and ton account using the `getAccount()` method.
+. Send ETH and `await` the transaction.
+. Send TON and `await` the transaction.

	## Example: Registering Multiple Wallets
	## Register Multiple Wallets


		## Installation

		Install the wallet managers for the blockchains you want to support:


		### Parameters

		The `registerWallet` method requires three arguments:


		## Handling Responses

		The `sendTransaction` method returns a transaction result object. The most important field is typically `hash`, which represents the transaction ID on the blockchain. You can use this hash to track the status of your payment on a block explorer.

WDK Core Documentation Refactor #64

Are you sure you want to change the base?

WDK Core Documentation Refactor #64

Conversation

ihsraham commented Jan 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Resolved Issues

1. Replaced Unavailable TON Bridge

2. Corrected Failover Middleware

Corrections & Value Additions

2. Configuration Corrections (TON)

3. Functional Verification Fixes

4. Visual & Style Improvements

File Changes

Verification Report

Uh oh!

lucas-tortora left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lucas-tortora left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

ihsraham commented Jan 17, 2026 •

edited

Loading